home *** CD-ROM | disk | FTP | other *** search
- .TOPIC:
- Virtual Script Language (VScript)
-
- VBBS 6.12 Documentation -- 10-1
-
-
- ╔════════════════════════════════════════════════════════════════╗
- ║ CHAPTER TEN VIRTUAL SCRIPT LANGUAGE <VSCRIPT> ║
- ╚════════════════════════════════════════════════════════════════╝
-
- SCRIPT LANGUAGE INTRODUCTION
- ════════════════════════════
-
- One of the features that makes VBBS unique is its script
- language compiler - VCOM.EXE. Along with the built-in command
- interpreter in VBBS, it allows you to make changes to your BBS
- quickly and easily. The scripts are nothing more than a series
- of commands listed in a plain ASCII text file, and you don't
- even need to be a programmer to write one. All you need to cre-
- ate scripts are a text editor or word processor that allows you
- to save in ASCII format (see your word processor documentation
- for more info) and a little patience. In no time, you will be
- writing up scripts and swapping them with other VBBS sysops like
- a pro. Scripts are generic to both the DOS and OS/2 versions.
-
-
- GENERAL RESTRICTIONS
- ════════════════════
-
- The VBBS script language has only one major restriction;
- there can only be a total of 7 'tokens' on a line. A token is
- defined as either a single unspaced series of characters (for
- example, a command or a number) or any group of characters and
- spaces surrounded by single or double quotes (also called a
- "string".) The script language is NOT case-sensitive; any
- capitalization used in this text is not required and is done
- only for clarity.
-
- All the scripts that you create should be placed into your
- scripts directory as defined in VCONFIG - PATHS Configuration;
- see Chapter 2 for more information on setting your paths.
-
- The only other restrictions pertain to names. All of your
- script files MUST have the extension .V and all of your names
- for variables must begin with a '$', e.g., $variable.
-
-
- SCRIPT COMPILER (VCOM.EXE)
- ══════════════════════════
-
- The program VCOM.EXE is the compiler that prepares your
- script file for use by VBBS's interpreter. It takes the script
- file that you have created and builds the two files that VBBS
- actually uses from it. These two files have the same name as
- the script file but have .LIT and .COD as their extensions.
-
- Compilation of a script is accomplished by changing to
- your scripts directory and executing the command line:
-
- VCOM <script name>
-
-
-
- VBBS 6.12 Documentation -- 10-2
-
-
- You do not need to use the extension to compile the script.
- The compiler can detect some errors in the script file during
- the compilation. These errors are predominantly related to the
- commands that 'jump' around within a script. These commands
- are GO, TEST, TESTVAL, CALL, and BREAK. If an error is found
- the compiler will abort and you will need to go into your
- script to correct the error.
-
-
- COMMAND FORMAT
- ══════════════
-
- All commands will be listed in the form:
-
- Command Name -> Command Syntax.
- <description of command here>
-
- The following conventions will be used in all command syntax
- in this document:
-
- COMMAND - All commands will be in capitals and must be
- typed in the format shown (see the note below.)
- <label> - A single word, no quotes or spaces.
- <variable#> - Any variable name (only).
- <number#> - Any numeric value (only).
- <string#> - A string value ("aBc 123") or any variable name.
- <value#> - A numeric value or any variable name that is
- used to store numeric values.
- <pathfile#> - A legal DOS filename including path information.
- If the path is excluded it will default to the
- BBS' main directory. A variable that stores the
- correct path/filename info may also be used.
- <filename#> - A legal DOS filename excluding path information.
- Commands that use this have the path info set
- automatically. A variable that has the filename
- stored in it may also be used.
- <prompt> - Either a text string or a variable name. Most
- of these are optional, so use them only if you
- want them.
- <relation> - Any of the following, but see the specific com-
- mand for verification:
-
- = Equal to <> Not equal to
- > Greater than >= Greater than or equal to
- < Less than <= Less than or equal to
-
- <option> - The value of this item is command-specific.
- <token#> - Any single item; see section 1.2 for a complete
- definition of a token.
-
- Note: If the command name is followed by a '<---' then the
- syntax for the command is just the command name.
-
-
-
- VBBS 6.12 Documentation -- 10-3
-
-
- SPECIAL VARIABLES/CONSTANTS
- ═══════════════════════════
-
- The script language contains the following restricted
- variables, which are read-only:
-
- $AGE - Age of user.
- $ANSI - Stores the user's current graphics setting. Set
- to OFF if using ASCII, ON if using ANSI, and ENH
- if using PDM's.
- $AVAILABLE - Stores the sysop availability flag. Y if sysop is
- available, N if not.
- $BAUD - Stores the user's connect speed.
- Returns "" if logged into node 0 (or other local
- node) and returns "CONSOLE" if logged in locally
- from the WFC screen.
- $BBSNAME - Stores the BBS' name, as shown in VCONFIG.
- $BELL - Stores ASCII code 7, causes a beep when printed.
- $BIRTHDATE - User birthdate in same format as $DATE.
- $BS - Stores ASCII code 8, causes the cursor to back up
- 1 space on current line when printed. It is not
- a destructive backspace.
- $CLEAR - Stores <CTRL>-<L> for ASCII users, stores the ANSI
- clear screen code for others when printed.
- $<color> - These nine variables are reserved as color codes:
- $RED, $BLUE, $CYAN, $GREEN, $YELLOW, $MAGENTA,
- $WHITE, $BLACK, and $NORM. See section 3.3 for
- more information.
- $CR - Stores ASCII code 13, causes a carriage return
- when printed (moves to column 1, current line.)
- $CREDITS - Number of credits user has.
- $CRLF - Causes both a $CR & $LF when printed (moves to
- column 1 of the next line.)
- $DATE - Stores the current system date as MM-DD-YYYY.
- $EXTRAx - The users extra variables values are stored in
- $EXTRA1 thru $EXTRA8. They can be changed with
- the SETEXTRA command. See section 8.2 for info.
- $FLAGS - This contains the list of all active general
- flags of the current user. Use the INSTR command
- with $FLAG and you will know if a particular flag
- is on if the result is non-zero. You can change
- the value of a flag with the SETFLAG command. See
- section 8.2 for info.
- $HANDLE - User's handle.
- $LF - Stores ASCII code 10, causes a linefeed when it's
- printed (same column position, next line.)
- $MAXTIME - Maximum minutes per day.
- $NAME - User's real name.
- $NODE - Stores your VirtualNET node # as set in VCONFIG.
- Default is 0 if you are not in VirtualNET.
- $PAGE - Number of lines to print before pause.
- $PORT - Returns present channel # of user (not COM port!)
- $SECURITY - User's security level, 250 and up is considered
- Co-sysop/Sysop access. Use TESTVAL and this
- variable to implement your own security.
-
-
- VBBS 6.12 Documentation -- 10-4
-
-
- $SYSOP - Stores the sysop's name as set in VCONFIG.
- $TEXTPATH - Stores the path to your TXT directory.
- $TIME - Stores the current system time.
- $TIMELEFT - Number of minutes left for this session.
- $TIMEON - Number of minutes on for this session.
- $TIMESON - Total number of logons for the user.
- $TOTALMIN - Total number of minutes on since first logon.
- $USER - User's account number.
- $VIDEOMODE - This stores values similar to $ANSI, only they are
- #'s instead of words. Set to 0 if using ASCII, 1
- if using ANSI, 2 if using PDM's, and 3 if using
- VGIX.
-
-
- INTERFACING WITH VBBS
- ═════════════════════
-
- There are only two ways that you can run a script. You can
- either run the script from a function block or LINK to it from
- another script. The former is covered here and the latter is
- covered in section 7.3 - Passing Control.
-
- Go into the function block you wish to have run the script
- and add the following line on any but the first two lines in the
- .FB file:
-
- Z 001 2 Scripter
- | | | ^------This is the script name, NO extension.
- | | ^----------This is the command type that tells VBBS it is
- | | running a script. See section 7.3
- | ^-------------This is the SL to be able to use the key (and
- | run the script.)
- ^----------------This is the key to press at the menu to load
- and run the script.
-
-
- PREPACKAGED SCRIPTS
- ═══════════════════
-
- --> IMPORTANT NOTE: This section is best read after reading
- through the entire file but is included here
- to maintain the structure of this document.
- Do not let the unknown terms interfere with
- your reading, as they will all be explained
- elsewhere.
-
- There are many script authors out in the BBSing community
- that have written all sorts of scripted programs to perform prac-
- tically everything you could ever want. The most difficult part
- of using a script is knowing how to install it. What you should
- do first is pull up the script and look for comments that explain
- the script. Some will contain complete sets of instructions,
- while others will contain no comments at all. If the script con-
- tains few or no comments, then what you will need to do is:
-
-
- VBBS 6.12 Documentation -- 10-5
-
- 1> Make sure that all EXIT and LINK statements point to
- FB's or scripts that you actually have. If all else
- fails you can set all of these statements to EXIT
- to your main FB file.
- 2> Look for any statements that use file commands. Be
- sure to change these to valid paths on your system.
- 3> See if the script has any RET lines. If it does,
- try to find the CALL statements to the labels that
- appear a few lines before the RET.
-
- After you have done these steps you will then have the info you
- need to determine how the script should be used. If the script
- has no EXIT or LINK statements, or the script has a RET line with
- no CALL statement, then you must make the script part of an exis-
- ting one. The easiest way to do this is to just block-copy the
- entire script in before your final EXIT or LINK statement in your
- script if it has no unmatched RET statements.
-
- If there is an unmatched RET statement, then installing
- the new script is even easier. Somewhere in your script you need
- to add a CALL <label> statement with <label> being the label at
- the start of the new script. Then just add as the last line of
- your script the line '& <script name>'. You should be able to
- compile and run it at this point. Just remember, 'Nothing is
- Guaranteed!', so if you have a problem with a script and you
- can't get it to work try to either pick the code apart (if you
- can) or hop onto any VirtualNet BBS that carries a script dis-
- cussion sub and ask a few questions (or a few hundred, as
- needed). One of the script gurus may be able to help you out,
- and you might even be able to get in touch with the author.
-
-
-
-